docs: 补充 MPC 钱包余额可用性模型、资金锁定与 BTC/UTXO 说明并优化 12007/30010 错误码指引#369
Open
rcsh1 wants to merge 1 commit into
Open
Conversation
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
意图
根据
developer文档仓库中 7 个工单(严重程度:medium,反复出现的理解混淆,confidence 0.87,时间跨度 2026-01 至 2026-04)识别出的 7 个文档问题,集中在账户余额可用性如何建模以及资金如何被锁定这两方面。本次变更主要在balance-amounts.mdx中补充余额可用性模型、资金锁定、BTC/UTXO 相关说明、支付余额类型以及「余额不足」排查指引,并优化错误码 12007/30010 的描述与处理建议。变更摘要
v2/guides/mpc-wallets/balance-amounts.mdx:新增「Balance availability model」(映射using_amount/locked_amount/spendable到公开字段data.balance.pending/locked/available并给出spendable计算公式)、「Fund locking」(创建即锁定、释放条件、UTXO 跨地址并发锁定)、「Bitcoin and UTXO considerations」(充币后索引延迟导致可用余额为 0、按代币配置的尘埃阈值与错误 30010、UTXO 归集建议)、「Payment balances」(total = available + frozen)以及「Troubleshooting insufficient balance」决策树,解决工单反映的余额不足却无法定位、UTXO 提币失败、错误码含义不清等问题。v2_cn/guides/mpc-wallets/balance-amounts.mdx:同步上述全部新增章节的简体中文版本,章节锚点与术语与英文版对应。snippets/error-codes.mdx:完善错误码 12007/30012 的处理建议(区分当前余额与可用余额、链接到 balance-amounts 指南、提示极小金额可能改为 30010),并补充 30010 描述(尘埃阈值按代币配置、与 12007 的区别)。snippets/error-codes-cn.mdx:同步 12007/30012 与 30010 的简体中文描述。API spec edits: 无(未改动任何 OpenAPI/spec 源文件)。
API spec sync: 无。
待确认事项
以下事实在文档中被有意省略或以保守措辞处理,合入前需人工与代码/规范核实其权威性:
total/available/frozen三类余额的公开规范字段名,以及 MPC 钱包余额指南是否为其正式归属页面(还是仅交叉链接),需与 Payment 公开规范核对。spendable = 链上余额 - using_amount - 待合规筛查金额 - 净冻结金额是否适合对外部开发者公开,需确认。